Introduction/Description/Raison 'd Etre
Introduction

ViewBar is a multithreaded text file viewer implemented as an Application Desktop Toolbar, like the Windows 95 taskbar.  It has an integrated file viewer/editor, file finder and grep (find text patterns in specified files) utility, which all run in their own user interface threads.  It also supports Windows 95 file type associations, so non text files which have a file association defined for their extension may also be viewed with other external viewers.  Viewbar also provides a tasklist of currently open viewers allowing quick access to all open files.

My original reason for writing ViewBar was that, when programming, I often wanted to view or copy text from source files other than the immediate working set that I currently had open in the programming environment (Visual C++ normally, Visual Basic sometimes), and I needed a quick way of opening these files.  Originally I used to use the venerable MSDOS LIST in a DOS box, but that was rather inconvenient and clumsy, and it didn't support long filenames which I use all the time, so after the advent of Windows 95 and the Appbars introduced in the new user interface, I decided that Appbars would be an ideal way to allow quick access to a file viewer.  While I wrote the program originally as a programming aid, it would probably be useful to many other types of users requiring quick viewing or editing of text files.

Another requirement, especially important when viewing many files,  was that there be some easy way to access all open viewers so I decided a tasklist for all open viewers would be a desirable feature.  This tasklist should support setting focus to a user selected viewer, killing a user selected viewer, minimizing all viewers, cascading all viewers and killing all viewers.

Before viewing a file, one sometimes needs to find it, which is why I also implemented an integrated file finder with support for date and file size filtering.  Another common requirement is to find all files containing some text pattern which was why I converted the Free Software Foundations GNU Grep V2 to Win32 (using WIN32 memory mapped files to improve performance).  Grep is particularly useful when browsing the MFC source code to try and figure out why your program has just ASSERTed.  Both Grep and the File Finder allow viewing of the files found by double clicking on it, and in Grep's case jumping to the line number in the file where the text pattern was found.  I have also included the Win32 Grep source code as per the GNU copyleft agreement (which many of the other people doing GNU conversions seem to have ignored as the their so called source is just the original Unix source).  See the Technical Details Topic  and the readme file in the GnuGrep directory for more details.

I would also welcome any suggestions or bug reports.  Please see the Contacting the Author  topic for details of how to contact me.


ViewBar Application Toolbar

The Viewbar Application Toolbar is the nerve centre of the Viewbar application.  It is from here that files to be viewed are entered or finder or grep utilities are launched.

The Appbar may be docked at any screen edge, although docking at the top or bottom looks better, or it may be used as a floating Appbar ie a normal window with a small titlebar.  It can also optionally have a icon in the Windows 95 (and NT 4) system tray, which is particularly useful when using it as a floating Appbar.  See the Viewbar Properties  topic for more information on properties such as enabling/disabling the system tray icon.

ViewBar Context Menu

The ViewBar context menu appears if you right click while in the ViewBar window) or by right clicking the ViewBar icon in the system tray.  You can :

Force Redraw of ViewBar	- Normally only used if you encounter a problem when Viewbar is hidden when, due to a fairly rarely occurring bug in Windows 95 you may have problems getting it to re-appear.

Properties	- Display the Viewbar Properties  sheet.

Help Contents	- Display the ViewBar Help contents page.

About	- Display the ViewBar About Screen.

Exit	- Close ViewBar.

Current Directory and Set Current Directory Button

ViewBar uses the current directory paradigm also present in command line shells in DOS and Unix.  This means that there is a current directory, which you may change, which is used when accessing files to specify the directory in which to open the file.  This means that once you have set the current directory to the directory in which the files you want to view reside, you need only specify their file names when typing in their name in the File Name/Path edit control.  Of course you can still specify files in a directory other than the current directory by typing in the full path of the file into the File Name/Path edit control.  See the ViewBar Properties  topic to see how you can modify the usage and setting of the current directory.

To change the current directory type in the full path of the directory into the Current Directory edit control and press the Set Current Directory button or press <ENTER> or press <TAB>.  You may also use the Browse button to find files to view.

File Name/Path

Use this edit control to specify the file to view.  If you type in a file name on its own without any matching files then the file you wish to open is assumed to reside in the current directory as specified above.  If you type in a path name including drives and/or sub-directories then the file is opened using the path you specify.  By default specifying a full path for a file does not change the current directory, but you can modify this behaviour if the 'Change CurDir when Full Path Entered' option is selected in the Viewbar Properties  property sheet.

You may also enter a wildcard in the filename edit control.  If you do this a file open dialog using your wildcard as a filter is opened, and you may use this to browse and select files matching your file specification (for example INV*.DOC).

View Button

Use this button to open a viewer of the file you specified in the File Name/Path edit control and/or the current directory.  This is the default button so pressing <ENTER> will automatically activate it (unless you are in the Current Directory edit control where pressing <ENTER> will instead change the current directory).

Viewers Tasklist

Browse For Files Button

Press the Browse for Files button to display a file open dialog allowing you to browse for and select a file to view instead of typing the file name and  directory.  The file open dialog will have a number of preset filters eg Readme Files (*.txt;*.doc;*.diz) and so on.  You may also customize these filters (see ViewBar Properties).

Find Files

Grep


Viewers TaskList Button

Pressing the Viewers TaskList Button displays a dialog listing all current viewer/edit threads by the file name of the file they are viewing.

To activate (bring to front) a particular viewer, select it by clicking  on the filename, then click Activate, or simply double click on the file name.

You can cascade all viewer windows by pressing the Cascade button.  Similarly you can minimize all viewers by pressing the Minimize All button.

To kill a viewer select it by clicking on the file name and then press the Kill button.  You can also kill all viewers by clicking the Kill All button.  In both cases you will first be asked to confirm your selection.

Press Close to close the Viewers Tasklist dialog.


Find Files

Press the Find Files button to start a file finder dialog and thread.

Specifications

Enter the file specifications to search for.  If you have multiple specifications separate them using a semi-colon ( ; ).  A history of previous specifications you entered is also available by opening the list box portion of the combo box by clicking on the down arrow in the specifications combo box.

Example :	*.DOC;*.XL;*.MDB

Add Directory

Use this edit control to enter start directories from which to initiate the search.  After entering a directory press <ENTER> or press the Add button to add the directory to the list of initial directories appearing below.

If you do not know the name of a directory press the browse button

This will display the Windows 95 shell Browse Computer dialog which you may use to select a directory.

Starting Directories

This displays all the starting directories you entered into the Add Directory edit control.  You may select a starting directory by clicking on it and then press the adjoining Del Dir button to delete that directory, or press Clear to clear all starting directories.

Show Special Files

You may enable or disable finding system, hidden and/or read only files by selecting or deselecting the appropriate check box.

Dates Between

You can choose to only display matching files whose modification date falls between the two dates specified here.  Enter the dates in the format specified in your Windows 95 regional settings in the control panel.  In the US this will probably be in the form MM/DD/YYYY, in the rest of the civilized world it would probably be DD/MM/YYYY or YYYYMMDD.

File Sizes Between

You can choose to only display matching files whose file size falls between the two values specified here.

Start Search

Click the Start Search button to start searching.  While searching the caption on the Start Search button will change to Stop Search.  Press the button again to abort the search.

Close

Press the Close button to close the file find dialog.

Help

Click the Help button to see this help topic.

Results

After the search is complete the results will be displayed in the results list control.  To activate a viewer on a file displayed in the results list control, double click on the file name of the file you wish to view.

To print the results use the Print... option on the File menu.


Grep

Press the Grep Button to start a grep dialog and thread.

Pattern

Enter the text pattern to search for.  This may also be a regular expression.

You may have noticed that you can enter multiple lines for the pattern; this only applies when the Grep algorithm being used is Fgrep, in which case each line is treated as a separate pattern and all occurrences of any  lines in the pattern edit control will be found, that is, an and condition is applied.

Specifications

Enter the file specifications to search for.  If you have multiple specifications separate them using a semi-colon ( ; ).  A history of previous specifications you entered is also available by opening the list box portion of the combo box by clicking on the down arrow in the specifications combo box.

Example :	*.CPP;*.C;*.H

Add Directory

Use this edit control to enter start directories from which to initiate the search.  After entering a directory press <ENTER> or press the Add button to add the directory to the list of initial directories appearing below.

If you do not know the name of a directory press the browse button

This will display the Windows 95 shell Browse Computer dialog which you may use to select a directory.

Match Case

If this check box is selected, Grep will exactly match the case of the pattern when comparing text during the search process.  If this check box is in the unselected state, Grep will ignore case when comparing.

Match Whole Words Only

When this check box is selected Grep the pattern will be assumed to be a whole word and only lines with full words (not parts of a word) matching the pattern will be displayed.  If this check box is unselected lines containing words which contain the pattern will also be displayed.

Example

If the pattern is 'sex' and match whole words is selected then only the word 'sex' will be found; if match whole word is off then words containing sex such as sextant or sexton will also be displayed (Is everyone in the class awake again ?)

Match Whole Lines Only

This is the same as the Match Whole Words option except that the entire line entered must be matched (including whitespace).

Output Byte Offset

When this check box is selected the offset into the file where the match occurs will be displayed along with the line number.

Display Filenames Only

When this check box is selected Grep will only display the filename once and no other line number information if  there is one or more matches of the pattern in the file.

Count Matches Only

When this check box is selected Grep will display only the filename and the number of matches which occurred in that file if  there is one or more matches of the pattern in the file.

Display Non-Matching Lines

Display lines which do not match the pattern.  Warning : This could generate a large amount of output.

Display Non-Matching Files

Display filenames only of files which do not contain the specified pattern.

Suppress Error Output

Do not display errors which may have occurred when attempting to open files during the Grep process.

Context Lines Before

Number of lines before the matching line to print in addition to the matching line.  This can often help you to filter out the matches you are interested in by seeing the context in which the matching line was used.

Context Lines After

Number of lines after the matching line to print in addition to the matching line.  This can often help you to filter out the matches you are interested in by seeing the context in which the matching line was used.

Grep Algorithm

Specify which Grep algorithm to use.

Choose from :

•	GNU E-Grep	- GNU extended Grep with support for extended regular expressions.

•	POSIX E-Grep	- POSIX compliant Grep

•	Fgrep	- Allows multiple pattern lines with each line treated as a separate pattern and all occurrences of any of the pattern lines will be found, that is, an and condition is applied.

Recurse Sub-Directories

When this check box is selected Grep will search match files in succeeding sub-directories of the start directory(ies) you specified.

Grep Button

Click the Grep button to start.  While Grep is working the caption on the Grep button will change to Abort Grep.  Press the button again to abort Grep.

Close

Press the Close button to close Grep.

Help

Click the Help button to see this help topic.

Results

After Grep is complete the results will be displayed in the results list control.  To activate a viewer on a file displayed in the results list control, double click on the file name of the file you wish to view.  The viewer will be opened at the line number at which the match occurred.

NOTE : The !@$#^%& (!=F, &=G) Rich Edit Control used in the viewer counts word wrapped lines as multiple lines, so if you enable word wrap (see ViewBar Properties) the line number will be wrong.  This wasted a lot of my time while developing, trying to figure out what was wrong with the viewer !

To print the results use the Print option on the File menu.


Regular Expression

A regular expression is a pattern that describes a set of strings.  Regular expressions are constructed analagously to arithmetic expressions, by using various operators to combine smaller expressions.

Grep understands two different versions of regular expression syntax: ``basic'' and ``extended.'' In GNU grep, there is no difference in available functionality using either syntax.  In other implementations, basic regular expressions are less powerful.  The following description applies to extended regular expressions; differences for basic regular expressions are summarized afterwards.

The fundamental building blocks are the regular expressions that match a single character.  Most characters, including all letters and digits, are regular expressions that match themselves.  Any metacharacter with special meaning may be quoted by preceding it with a backslash.

A list of characters enclosed by [ and ] matches any single character in that list; if the first character of the list is the caret ^ then it matches any character not in the list.  For example, the regular expression [0123456789] matches any single digit.  A range of ASCII characters may be specified by giving the first and last characters, separated by a hyphen.  Finally, certain named classes of characters are predefined.  Their names are self explanatory, and they are [:alnum:], [:alpha:], [:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:], [:space:], [:upper:], and [:xdigit:].  For example, [[:alnum:]] means [0-9A-Za-z], except the latter form is dependent upon the ASCII character encoding, whereas the former is portable.  (Note that the brackets in these class names are part of the symbolic names, and must be included in addition to the brackets delimiting the bracket list.) Most metacharacters lose their special meaning inside lists. To include a literal ] place it first in the list.  Similarly, to include a literal ^ place it anywhere but first. Finally, to include a literal - place it last.

The period . matches any single character.  The symbol \w is a synonym for [[:alnum:]] and \W is a synonym for [^[:alnum]].

The caret ^ and the dollar sign $ are metacharacters that respectively match the empty string at the beginning and end of a line.  The symbols \< and \> respectively match the empty string at the beginning and end of a word.  The symbol \b matches the empty string at the edge of a word, and \B matches the empty string provided it's not at the edge of a word.

A regular expression matching a single character may be followed by one of several repetition operators: ? The preceding item is optional and matched at most once. * The preceding item will be matched zero or more times. + The preceding item will be matched one or more times. {n} The preceding item is matched exactly n times. {n,} The preceding item is matched n or more times. {,m} The preceding item is optional and is matched at most m times. {n,m} The preceding item is matched at least n times, but not more than m times.

Two regular expressions may be concatenated; the resulting regular expression matches any string formed by concatenating two substrings that respectively match the concatenated subexpressions.

Two regular expressions may be joined by the infix operator |; the resulting regular expression matches any string matching either subexpression.

Repetition takes precedence over concatenation, which in turn takes precedence over alternation.  A whole subexpression may be enclosed in parentheses to override these precedence rules.

The backreference \n, where n is a single digit, matches the substring previously matched by the nth parenthesized subexpression of the regular expression.

In basic regular expressions the metacharacters ?, +, {, |, (, and ) lose their special meaning; instead use the backslashed versions \?, \+, \{, \|, \(, and \).

In egrep the metacharacter { loses its special meaning; instead use \{.


File Viewer/Editor

The Viewer is an internal File viewer/editor based on the Windows 95 Rich Edit Control.  Most of the commonly required commands and operations also occur in the toolbar.

Changing Read Only Status

If you wish to edit the file you are viewing you can toggle its Read Only status by clicking the Read Only option on the File menu or pressing the toolbar shortcut button

Navigation

Use all the normal cursor keys and page up page down etc to move around in the files.  The status bar at the bottom will display the current line number you are on and the percentage of the total file number of lines that the line you are on is.

You may also goto to a specific line number.  You can do this either by typing a number into the line number combo ( [image]) and pressing <ENTER> (or press the Goto Toolbar Line No. Button [image] ) or select the Goto Line... option in the Edit Menu (or use its Toolbar shortcut (Line no. Dialog) button [image] ).

Selecting and Clipboard Operations

You can select text in the normal way using the mouse with the left button down or using shift and the cursor keys.   If the viewer is in Read Only mode then you may only Copy text and Select All text, the other options (cut and paste) are disallowed.  The clipboard operations are :

Operation	Menu	Toolbar

Cut *	Edit/Cut

Copy	Edit/Copy

Paste*	Edit/Paste

Select All	Edit/Select All

* only available if the Read Only Property is disabled.

Searching for Text

To search for text using the toolbar enter the search text into the Text to Find combo box ( [image]) by clicking  on it and then typing in the search text.  Press Enter or click the Find Next button [image] or press the Find Next accelerator key F3 to find the first occurrence.  Repeat this to find further occurrences.  To leave the Text to Find combo press Tab at any time or click in the text view area with the mouse.

To find text using the Find Dialog select the Find... option in the Edit Menu or use the toolbar shortcut button [image].  If you cancel the Find dialog you can still search for the last text you entered by pressing F3.

Replacing Text

 This option is only available if you have set the Read Only mode off.

To search for and replace text select the Replace... option on the Edit menu or press the Toolbar shortcut button [image].

Font Format Option

This option is only available if Read Only Mode is off.

You must first select the text you want to change the font for (or press Ctrl-A to select all).  Then press the toolbar button or select the Font... option in the format menu.  Select the font you want in the Select Font dialog.

Paragraph Format Option

This option is only available if Read Only Mode is off.

You must first select the paragraphs you want to change the formatting for (or press Ctrl-A to select all).  Then press the toolbar button or select the Paragraph... option in the format menu.   The resulting dialog will allow you to modify the left and right indentation and the indentation for the first line of a paragraph.

Tab Stops Format

You must first select the paragraphs you want to change the formatting for (or press Ctrl-A to select all). Then press the toolbar button or select the Tabs... option in the format menu.   The resulting dialog will allow you to modify the positions of the tabstops.  The default is two characters of the non proportional courier font.

File Options

If you have disabled the Read Only option then you can save any changes you make by selecting Save on the File menu or pressing the Save toolbar shortcut [image].

You can also save the file under a new name using the Save As... option under the File menu.

You can open another file using the Open... command under the File menu or pressing the open toolbar shortcut button [image].

You can create a new file by selecting New on the File Menu or pressing the New toolbar shortcut [image].

Printing

You can Print the file by selecting Print from the File menu or pressing the Print toolbar shortcut button [image].  You can also do a rough print preview by selecting Print Preview... on the File menu.

Help

To display this help select Help from the Help menu or press the help toolbar button [image].

Properties

The Properties property sheet can be enabled either by selecting the Properties... option from the ViewBar context menu (which appears when you right click in the ViewBar window) or by right clicking the ViewBar icon in the system tray.  There are currently two sheets, one for ViewBar itself and one to set the file viewers properties.

ViewBar Properties

Always On Top

This option  specifies whether ViewBar will always appear above all other windows in the z-Order.

AutoHide

If this option is enabled ViewBar will shrink out of sight when not in use and will only slide back into view when the mouse cursor is moved to the edge where ViewBar is currently docked.

Note there are still some bugs in Windows 95 with autohide toolbars although these only occur under special circumstances.  If you do encounter a problem getting ViewBar to display properly you can select the first menu option on the context menu viz Force Redraw to redraw ViewBar or double click on the ViewBar icon in the system tray.

Check for File Type Association

If this option is enabled the specified file to be viewed will first have its extension checked by the Windows 95 shell to see if there is a registered program to open the file with.

Except For

Sometimes you may want to ignore file associations for some extensions.  For example the Windows 95 install sets the default program for .TXT files as NOTEPAD, whereas if you are using ViewBar you would probably prefer to use the ViewBar viewer for these TXT files.

To use this feature :

•	To add an extension which must not be checked type it into the ignore edit control then press <ENTER> or click the Add button.

•	To delete an extension highlight the exyension to be deleted in the list box by clicking on it, then press <DEL> or click the Del button.

•	To clear all ignore extensions click the Clear button.

Ask whether  to use File Type Association

If the previous option is enabled and there is a program registered for the files extension then if this option is enabled then you will be prompted whether to open the file with the registered program or use the ViewBar viewer.

Change CurDir when Full Path Entered

By default with this option disabled the current directory only changes when you type in a new current directory.

With this option enabled if you type in a full path name for a file and no just a filename, then the current directory is changed to the drive and/or directory of the path of the file.

Use External Viewer

If this option I enabled then a user specified file viewer is used instead of the ViewBar default internal viewer.  Note if you do use an external viewer the  viewer tasklist will not show the viewers.

External Viewer

Specify the path and name of the viewer to use.  Use the browse button [image]  to search for the viewer.

Maximum CurDir/Maximum Path History

These two options specify how many previous current directories and paths/filenames to store in the current directory and path combo boxes.

Icon in System Tray

If this option is enabled the ViewBar icon will be displayed in the system tray in the Windows 95 taskbar.

Customize Browse Filters

Click on this button to display a dialog which allows you to add or delete filters used in the file open dialog of the Browse option.

To add a new filter enter a description in the Descriptions edit control and file specifications separated by semi-colons eg *.cpp;*.c;*.h in the Extension edit control then press the Add button.

To delete a filter highlight it in the list box then press Del or press the Delete button.

When you are finished press OK to save the changes.

Viewer Properties

The Viewer Properties Property Sheet allows you to set defaults for the ViewBar internal file viewer/editor.  Click on the Viewer tab to switch to this sheet.

 Enable Word Wrap

Enable this option to set word wrap on when viewing the file.

NOTE : The !@$#^%& (!=F, &=G) Rich Edit Control used in the viewer counts word wrapped lines as multiple lines, so if you enable word wrap the line number will be wrong.  This wasted a lot of my time while developing, trying to figure out what was wrong with the viewer !

Default to Read Only

When this option is enabled the viewer will start with the Read Only property enabled.  Disable this option if you would like to start all viewers with the Read Only property off.

Tab Size

Default tab size in spaces to use.  The default font used in the Viewer is non-proportional, and when reading program files which have been created with editors which use tabs instead of spaces, this option allows you to customize how the indentation of program lines and so on will look.


Distribution and Technical Addenda

Distribution

ViewBar is distributed as Freeware.  The only condition which applies is that, as specified in the GNU copyleft, if you distribute this program you must also distribute the accompanying GNU Grep source code.  For more info on the GNU distribution policy see the file COPYING in the GNUGREP sub-directory.  The CDirMatcher class I wrote (see Technical Addenda below) for directory processing which is included in the GNU source is also distributable under this license.

If however, after using this program, you are filled with an uncontrollable  desire to part with your money, send any donation you see fit to the Nelson Mandela Children's Fund (http://www.web.co.za/mandela/children).

I am currently uploading this program to Winsite and Simtel, but hopefully in the future I will also have a Web page where the latest version can be found.  The address will probably be something like http://www.tricom.co.za/~donaldm.

Technical Addenda

Development Tools

ViewBar was developed using Microsoft Visual C++ V4.1 and MFC 4 on a Pentium 90 with 32Mb of RAM and 1.2Gb+840Mb of disk space.

The help was authored using HelpBreeze Evaluation copy, since I decided to kill two birds with one stone and do an evaluation of the product for work purposes and create this help file at the same time.  Unfortunately there is a limit of 10 topics in the evaluation version so I have had to be rather miserly with topics.  Maybe if we decide to purchase the product, I will be able to produce a more luxurious help for the next version.

GNU Grep

The following section is aimed at developers who would like to use the Grep source in their own programs.  Note if you do use the source in your own programs you must also distribute it with your application.

The GNU Grep source is in the GNUGREP sub-directory under two further sub-directories.

The CL sub-directory contains the command line source code for a Win32 console version with some minimal changes to make it work under Win32.  These changes involved :

•	Changing the directory processing to use the Win32 FindFirstFile and FindNextFile API calls, as the UNIX version depended on the shell to do this (I suppose if you were running a Win32 version of bash, this would not be necessary).

•	Converting File reads to use memory mapped files to increase performance.  I'm not sure if some of the other ports do this, since this version seems faster on big files than some of the NT GNU Grep binaries which I downloaded (they didn't include the proper Win32 source so its hard to tell).

A future enhancement would be to change the directory processing to allow recursing sub-directories like the GUI version used in ViewBar does, perhaps using a -R switch.

The GUI sub-directory contains the GUI Win32 conversion.  Changes here included :

•	Directory processing done with a combination of the Find???File API calls and a CDirMatcher class I wrote to make wildcard, date, size and attribute matching easier and faster.  This class is redistributable under the same GNU copyleft agreement as GNU Grep.  (I actually wanted to use regex at first for the wildcard matching, but it was rather a nightmare attempting to translate the simple wildcards into regular expressions; also I did not want to use FindFirstFile/FindNextFile multiple times for multiple specs and then again for *.* to get sub-directories).

•	The output is redirected to a callback function which you may then use to output the grep results into list controls, grids or whatever.  Unfortunately this is not as generalized as I would have done if I had spent more time on it, as it depends on a CGrepView which is the View which calls the main grep function (a q & d way to provide a this pointer to the callback).  If you use this Grep version you may want to generalize it properly, or just knock together your own CGrepView.  The above applies to MFC, if you are using another framework, or not using a framework at all you will have to do some extra surgery.

•	There seemed to be lots of memory leaks, which I suppose is OK for a command line utility which exits after running so all memory used will  be freed, but is not as acceptable with a GUI form based utility which could be used multiple times before exiting.  To solve this problem I allocated a Win32 private heap at the beginning of the grep function and then ensured that all malloc calls were #defined to use this private heap (excepting some calls in regex.c which seem to do funny things with the stack) and then freed the private heap after the grep call completed.

•	Since the source uses so many global variables I only allow a single instance of the grep thread in ViewBar.  I might in the future attempt to use TLS for the global variables to solve this problem.


Contacting the Author/Suggestions and Bug Reports

My name is Donald Munro and my E-Mail address is : donaldm@tricom.co.za.

Postal Address	PO Box 13745

Humewood

Port Elizabeth

6013

South Africa

I would welcome any bug reports and/or suggestions for improvements.